home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 …ember: Reference Library / Dev.CD Dec 98 RL1.toast / What's New / Development Kits / AppleShare IP 6.1 SDK / ASIP User Authentication Module / Client UAM SDK / Headers / ClientUAM.h < prev   
Encoding:
C/C++ Source or Header  |  1998-10-26  |  13.6 KB  |  445 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        ClientUAM.h
  3.  
  4.      Contains:    Public Header file for the AppleShare Client UAM API 
  5.  
  6.      Version:    3.8
  7.  
  8.      DRI:        Leland Wallace
  9.  
  10.      Copyright:    © 1997 by Apple Computer, Inc., all rights reserved.
  11.  
  12.      Warning:    *** APPLE INTERNAL USE ONLY ***
  13.                  This file may contain unreleased API's
  14.  
  15.      BuildInfo:    Built by:            Leland Wallace
  16.                  With Interfacer:    3.0d3   (PowerPC native)
  17.                  From:                ClientUAM.i
  18.                      Revision:        5
  19.                      Dated:            7/17/98
  20.                      Last change by:    law
  21.                      Last comment:    • fixed a problem with the callback completeion routine
  22.  
  23.      Bugs:        Report bugs to Radar component "System Interfaces", "Latest"
  24.                  List the version information (from above) in the Problem Description.
  25.  
  26. */
  27. #ifndef __CLIENTUAM__
  28. #define __CLIENTUAM__
  29.  
  30. #ifndef __CONDITIONALMACROS__
  31. #include <ConditionalMacros.h>
  32. #endif
  33. #ifndef __MIXEDMODE__
  34. #include <MixedMode.h>
  35. #endif
  36. #ifndef __DEVICES__
  37. #include <Devices.h>
  38. #endif
  39. #ifndef __APPLETALK__
  40. #include <AppleTalk.h>
  41. #endif
  42. #ifndef __OPENTRANSPORT__
  43. #include <OpenTransport.h>
  44. #endif
  45. #ifndef __OPENTPTINTERNET__
  46. #include <OpenTptInternet.h>
  47. #endif
  48. #ifndef __OPENTPTAPPLETALK__
  49. #include <OpenTptAppleTalk.h>
  50. #endif
  51. #ifndef __ERRORS__
  52. #include <errors.h>
  53. #endif
  54. #ifndef __EVENTS__
  55. #include <Events.h>
  56. #endif
  57. #ifndef __AFPCLIENT__
  58. #include <AFPClient.h>
  59. #endif
  60.  
  61.  
  62.  
  63. #if PRAGMA_ONCE
  64. #pragma once
  65. #endif
  66.  
  67. #ifdef __cplusplus
  68. extern "C" {
  69. #endif
  70.  
  71. #if PRAGMA_IMPORT
  72. #pragma import on
  73. #endif
  74.  
  75. #if PRAGMA_STRUCT_ALIGN
  76.     #pragma options align=mac68k
  77. #elif PRAGMA_STRUCT_PACKPUSH
  78.     #pragma pack(push, 2)
  79. #elif PRAGMA_STRUCT_PACK
  80.     #pragma pack(2)
  81. #endif
  82.  
  83.  
  84. /* Error values*/
  85.  
  86. enum {
  87.     kUAMError                    = -5002,                        /* afpBadUAM*/
  88.     kNotForUs                    = -50                            /* paramErr*/
  89. };
  90.  
  91. /* UAM Class & Type values*/
  92.  
  93. enum {
  94.     kUAMStdClass                = 0,                            /* Standard UAM (8 byte password)*/
  95.     kUAMVarClearClass            = 1,                            /* variable length cleartext password*/
  96.     kUAMVarCryptClass            = 2,                            /* variable length encrypted password*/
  97.     kUAMUserDefClass            = 3                                /* Custom UAM*/
  98. };
  99.  
  100.  
  101. enum {
  102.     kNoPasswd                    = 1,                            /* Class 0, No User Authentication (Guest)*/
  103.     kCleartextPasswd            = 2,                            /* Class 0, Cleartext password (8 byte password)*/
  104.     kEncryptPasswd                = 3,                            /* Class 0, RandnumExchange (8 byte password)*/
  105.     kVarPasswd                    = 4,                            /* Class 1, variable length cleartext password*/
  106.     kVarEncryptPasswd            = 5,                            /* Class 2, variable length encrypted password*/
  107.     kTwoWayEncryptPasswd        = 6                                /* Class 0, two way randnum exchange (8 byte password)*/
  108. };
  109.  
  110. /* general constants*/
  111.  
  112. enum {
  113.     kMaxAFPCommand                = 576,
  114.     kStdPWdLength                = 8,
  115.     kMaxPwdLength                = 64
  116. };
  117.  
  118.  
  119. /* UAM Commands    */
  120.  
  121. enum {
  122.     kUAMOpen                    = 0,
  123.     kUAMPWDlog                    = 1,
  124.     kUAMLogin                    = 2,
  125.     kUAMVSDlog                    = 3,
  126.     kUAMChgPassDlg                = 4,
  127.     kUAMChgPass                    = 5,
  128.     kUAMGetInfoSize                = 6,
  129.     kUAMGetInfo                    = 7,
  130.     kUAMClose                    = 8,
  131.     kUAMPrOpen                    = 9,
  132.     kUAMPrAuthDlog                = 10,
  133.     kUAMPrAuth                    = 11
  134. };
  135.  
  136.  
  137.  
  138. /* config bits*/
  139.  
  140. enum {
  141.     kUsePWDlog                    = 0,                            /* The UAM wants to put up its own Password/PRAuth Dialog*/
  142.     kUseVolDlog                    = 1,                            /* The UAM wants to put up its own Volume Selection DIalog*/
  143.     kSupportsCP                    = 2,                            /* The UAM supports Changing the password*/
  144.     kUseCPDlog                    = 3,                            /* The UAM wants to put up its own Change Password Dialog*/
  145.     kUseUAMInfo                    = 4                                /* The UAM supports storing authentication info in UAMInfo*/
  146. };
  147.  
  148. /* All other bits are reserved and must be set to 0*/
  149.  
  150.  
  151. /* structs*/
  152.  
  153.  
  154.  
  155. struct ClientInfo {
  156.     short                             fInfoType;                    /* the type of ClientInfo*/
  157.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  158. };
  159. typedef struct ClientInfo ClientInfo;
  160.  
  161.  
  162. enum {
  163.     kAFPClientInfo                = 0,
  164.     kPrClientInfo                = 1
  165. };
  166.  
  167. struct AFPClientInfo {
  168.     short                             fInfoType;                    /* the type of ClientInfo (kAFPClientInfo)*/
  169.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  170.     short                             fConfigFlags;                /* the hi  short of the gestalt('afpt') response*/
  171.     short                             fVersion;                    /* the low short of the gestalt('afpt') response*/
  172.     short                             fNumAFPVersions;            /* the number of afp versions supported by this client*/
  173.     StringPtr *                        fAFPVersionStrs;            /* an array of afp version strings supported by this client*/
  174. };
  175. typedef struct AFPClientInfo AFPClientInfo;
  176.  
  177. struct PRClientInfo {
  178.     short                             fInfoType;                    /* the type of ClientInfo (kPrClientInfo)*/
  179.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  180.     FSSpec                             fPPDFile;                    /* the fsspec of the ppd file for the currently selected printer*/
  181. };
  182. typedef struct PRClientInfo PRClientInfo;
  183.  
  184. /* Callbacks:*/
  185.  
  186. /*
  187.    this Completion routine is called with the contextPtr passed in to
  188.    the OpenAFPSession() and SendRequest() calls, when one of these calls
  189.    completes. The result parameter contains the AFP result.
  190.    You cannot call any of the callback routines from this Completion
  191.    routine, so you can't do chained completion routines. This routine
  192.    will be called just like any other completion routine or notifier
  193.    so the usual rules apply.
  194. */
  195.  
  196. typedef CALLBACK_API( void , CompletionPtr )(void *message, OSStatus result);
  197.  
  198. /*    GetClientInfo()
  199.     Returns information about the Client, such as which versions of AFP are
  200.     supported and the various gestalt values. This call also returns the
  201.     default user name. If the infoType is not avaliable it will return nil.
  202.  
  203.     pascal    OSStatus    GetClientInfo(short infoType,ClientInfo    **infoPtr);        
  204. */
  205. struct UAMMessage {
  206.     long                             commandCode;
  207.     short                             sessionRefNum;
  208.     OSStatus                         result;
  209.     unsigned char *                    cmdBuffer;
  210.     unsigned long                     cmdBufferSize;
  211.     unsigned char *                    replyBuffer;
  212.     unsigned long                     replyBufferSize;
  213.     CompletionPtr                     completion;
  214.     void *                            contextPtr;
  215.     UInt8                             scratch[80];                /* scratch space for the client*/
  216. };
  217. typedef struct UAMMessage UAMMessage;
  218.  
  219. typedef UAMMessage *                    UAMMessagePtr;
  220.  
  221. enum {
  222.                                                                 /* commandCodes (for future expansion)*/
  223.     kOpenSession                = FOUR_CHAR_CODE('UAOS'),
  224.     kSendRequest                = FOUR_CHAR_CODE('UASR')
  225. };
  226.  
  227. /*    OpenSession()
  228.     Opens a session to the specified address. If you are using AFP, cmdBuffer MUST 
  229.     contain an AFP Login command. If you are using AFP the command buffer size is limited
  230.     to kMaxAFPCommand (576 bytes). Set endpointString to nil if default is desired 
  231.     (TCP only, it is ignored for AppleTalk connections (and may also be ignored on
  232.     rhapsody)). Leave completion & contextPtr nil for sync. Session reference number 
  233.     is returned in the sessionRefNum field.
  234.  
  235.  
  236.     pascal    OSStatus    OpenSession(OTAddress *, const char* endpointString, UAMMessagePtr);
  237. */
  238. /*     SendRequest()
  239.     Sends a command to the server. If the session is an AFP session, cmdBuffer
  240.     MUST contain an AFP command. If you are using AFP the command buffer size is limited
  241.     to kMaxAFPCommand (576 bytes). Leave completion & contextPtr nil for sync.
  242.     the Session reference number for this connection must be in the sessionRefNum field.
  243.                 
  244.     pascal    OSStatus    SendRequest(UAMMessagePtr);
  245. */
  246.  
  247. /*    CloseSession()
  248.     Closes the session denoted by the sessRefNum;
  249.  
  250.     pascal    OSStatus    CloseSession(short sessRefNum);
  251. */
  252.  
  253. /*    SetMic()
  254.     Sets the message integrity code key. If the connection supports using 
  255.     keyed HMAC-SHA1 for message integrity, the UAM may pass a key down
  256.     to the network layer using this call. 
  257.  
  258.     pascal    OSStatus    SetMic(short sizeInBytes, Ptr micValue);
  259. */
  260. #if GENERATING68K
  261. typedef CALLBACK_API( OSStatus , OpenSessionPtr )(OTAddress *addr, const char *endpointString, UAMMessagePtr message);
  262. typedef CALLBACK_API( OSStatus , SendRequestPtr )(UAMMessagePtr message);
  263. typedef CALLBACK_API( OSStatus , CloseSessionPtr )(short sessRefNum);
  264. typedef CALLBACK_API( OSStatus , GetClientInfoPtr )(short infoType, ClientInfo **info);
  265. typedef CALLBACK_API( OSStatus , SetMicPtr )(short sizeInBytes, Ptr micValue);
  266. typedef CALLBACK_API( void , EventCallbackPtr )(EventRecord *theEvent);
  267. #else
  268. typedef UniversalProcPtr                 OpenSessionPtr;
  269. typedef UniversalProcPtr                 SendRequestPtr;
  270. typedef UniversalProcPtr                 CloseSessionPtr;
  271. typedef UniversalProcPtr                 GetClientInfoPtr;
  272. typedef UniversalProcPtr                 SetMicPtr;
  273. typedef UniversalProcPtr                 EventCallbackPtr;
  274. #endif  /* GENERATING68K */
  275.  
  276. struct ClientUAMCallbackRec {
  277.     OpenSessionPtr                     OpenSessionUPP;
  278.     SendRequestPtr                     SendRequestUPP;
  279.     CloseSessionPtr                 CloseSessionUPP;
  280.     GetClientInfoPtr                 GetClientInfoUPP;
  281.     SetMicPtr                         SetMicUPP;
  282.     EventCallbackPtr                 EventCallbackUPP;
  283. };
  284. typedef struct ClientUAMCallbackRec ClientUAMCallbackRec;
  285.  
  286. struct VolListElem {
  287.     UInt8                             volFlags;                    /* volume flags*/
  288.     Str32                             volName;
  289. };
  290. typedef struct VolListElem VolListElem;
  291.  
  292. /* definitions for the volume flags*/
  293.  
  294. enum {
  295.     kMountFlag                    = 0,                            /* bit indicating this volume is to be mounted (set by the UAM)*/
  296.     kAlreadyMounted                = 1,                            /* bit indicating that the volume is currently mounted*/
  297.     kNoRights                    = 2,                            /* bit indicating that this user has no permission to use the volume*/
  298.     kHasVolPw                    = 7                                /* bit indicating that the volume has a volume password*/
  299. };
  300.  
  301. struct UAMOpenBlk {                                                /* called for UAMOpen & UAMPrOpen*/
  302.     StringPtr                         objectName;                    /* <-    server or printer name*/
  303.     StringPtr                         zoneName;                    /* <-    zone name or nil if no zone is present*/
  304.     OTAddress *                        srvrAddress;                /* <-    OT Address of the "server"    */
  305.     AFPSrvrInfo *                    srvrInfo;                    /* <-    for UAMOpen this is the GetStatus reply, for Printers ???*/
  306. };
  307. typedef struct UAMOpenBlk UAMOpenBlk;
  308.  
  309. struct UAMPWDlogBlk {                                            /* for the password dialog and prAuthDlog*/
  310.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  311.     unsigned char *                    password;                    /* <-    pointer to a Str64 containing the password*/
  312. };
  313. typedef struct UAMPWDlogBlk UAMPWDlogBlk;
  314.  
  315. struct UAMAuthBlk {                                                /* called for login and prAuthenticate*/
  316.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  317.     unsigned char *                    password;                    /* <-    pointer to a 64 byte buffer containing the password*/
  318.     OTAddress *                        srvrAddress;                /* <-    OT Address of the "server"    */
  319. };
  320. typedef struct UAMAuthBlk UAMAuthBlk;
  321.  
  322. struct UAMVSDlogBlk {                                            /* for the volume select dialog*/
  323.     short                             numVolumes;                    /* <-    number of volumes in the volume list*/
  324.     VolListElem *                    volumes;                    /* <-    the volume list*/
  325. };
  326. typedef struct UAMVSDlogBlk UAMVSDlogBlk;
  327.  
  328. struct UAMChgPassBlk {                                            /* for both the change password dialog and the change password call*/
  329.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  330.     unsigned char *                    oldPass;                    /* <-    pointer to a 64 byte buffer containing the old password*/
  331.     unsigned char *                    newPass;                    /* <-    pointer to a 64 byte buffer containing the new password*/
  332. };
  333. typedef struct UAMChgPassBlk UAMChgPassBlk;
  334.  
  335. struct UAMArgs {
  336.     short                             command;                    /* <-    UAM command selector*/
  337.     short                             sessionRefNum;                /* <->    session reference number*/
  338.     long                             result;                        /*  ->    command result*/
  339.     void *                            uamInfo;                    /* <-    pointer to a block of Auth Data*/
  340.     long                             uamInfoSize;                /* <->    size of the Auth Data*/
  341.     ClientUAMCallbackRec *            callbacks;                    /* <-    Callback record */
  342.     union {
  343.         UAMChgPassBlk                     chgPass;
  344.         UAMVSDlogBlk                     vsDlog;
  345.         UAMAuthBlk                         auth;
  346.         UAMPWDlogBlk                     pwDlg;
  347.         UAMOpenBlk                         open;
  348.     }                                 Opt;
  349. };
  350. typedef struct UAMArgs UAMArgs;
  351.  
  352. EXTERN_API( OSStatus )
  353. UAMCall                            (UAMArgs *                theArgs);
  354.  
  355.  
  356.  
  357. /* procinfos*/
  358.  
  359. enum {
  360.     kOpenSessionProcInfo = kPascalStackBased    
  361.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  362.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(OTAddress *)))        
  363.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(const char*)))        
  364.             | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(UAMMessagePtr))),        
  365.     
  366.     kSendRequestProcInfo =  kPascalStackBased    
  367.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  368.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(UAMMessagePtr))),        
  369.     
  370.     kCloseSessionProcInfo =  kPascalStackBased    
  371.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  372.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short))),                
  373.     
  374.     kGetClientInfoProcInfo =  kPascalStackBased    
  375.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  376.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))    
  377.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(ClientInfo **))),        
  378.     
  379.     kSetMicProcInfo =  kPascalStackBased    
  380.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  381.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))                
  382.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Ptr))),                
  383.     
  384.     kEventCallbackProcInfo =  kPascalStackBased    
  385.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(EventRecord *))),        
  386.     
  387.     kUAMCallProcInfo =  kPascalStackBased
  388.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  389.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(UAMArgs *)))            
  390. };
  391.  
  392. /* Resouce definitions
  393. */
  394.  
  395. enum {
  396.     kUAMName                    = 0,                            /* user visible name of the UAM*/
  397.     kUAMProtoName                = 1,                            /* protocol name of the UAM (sent to the server in the login cmd)*/
  398.     kUAMDescription                = 2,                            /* short description of the UAM (displayed in the dialog)*/
  399.     kUAMHelpBalloon                = 3                                /* Str255 for the Balloon Help item*/
  400. };
  401.  
  402.  
  403. enum {
  404.     kUAMFileType                = FOUR_CHAR_CODE('uams')        /* Type of the UAM file*/
  405. };
  406.  
  407. /* resource types*/
  408.  
  409. enum {
  410.     kUAMStr                        = FOUR_CHAR_CODE('uamn'),
  411.     kUAMCode                    = FOUR_CHAR_CODE('uamc'),
  412.     kUAMConfig                    = FOUR_CHAR_CODE('uamg')
  413. };
  414.  
  415. /* 'uams' resource IDs    */
  416.  
  417. enum {
  418.     kUAMTitle                    = 0,                            /* UAM Title string (shown in the UAM list)*/
  419.     kUAMProtocol                = 1,                            /* UAM protocol name*/
  420.     kUAMPWStr                    = 2,                            /* UAM description string (shown in the Password dialog)*/
  421.     kUAMBallHelp                = 3                                /* Balloon Help string for the Password dialog.*/
  422. };
  423.  
  424.  
  425. #if PRAGMA_STRUCT_ALIGN
  426.     #pragma options align=reset
  427. #elif PRAGMA_STRUCT_PACKPUSH
  428.     #pragma pack(pop)
  429. #elif PRAGMA_STRUCT_PACK
  430.     #pragma pack()
  431. #endif
  432.  
  433. #ifdef PRAGMA_IMPORT_OFF
  434. #pragma import off
  435. #elif PRAGMA_IMPORT
  436. #pragma import reset
  437. #endif
  438.  
  439. #ifdef __cplusplus
  440. }
  441. #endif
  442.  
  443. #endif /* __CLIENTUAM__ */
  444.  
  445.